feat(lamzu): add the Atlantis generation under CompX vendor id 0x3554 - #85

Adds the Lamzu Atlantis family — Atlantis OG V2, Atlantis Mini, Atlantis Mini Pro, Thorn, Maya and Paro of that generation — as a driver of its own.

These are not the Lamzu the existing driver handles. LamzuHidClient speaks the CompX page/command protocol on feature report 0 under vendor ids 0x373e and 0x37b0. The Atlantis generation is a different CompX stack entirely: vendor id 0x3554, report 8, interrupt reports, settings in a flash image addressed by byte offset.

That stack is already in this repo — it is what PulsarHidClient speaks to the Pulsar 4K receiver. Same pulsarPacketChecksum, same command ids, same flash offsets, same 50-step DPI encoding. So this adds no new framing code:

// src/lamzu/atlantis.ts
export const LAMZU_ATLANTIS_COMMAND = PULSAR_COMMAND;
export const LAMZU_ATLANTIS_FLASH = {
  ...PULSAR_FLASH,      // reportRate 0, currentDpi 4, liftOffDistance 10, …
  dpiStageCount: 2,     // fields Lamzu's firmware uses that the Pulsar driver never reads
  dpiStageColors: 44,
  buttonActions: 96,
  highPerformance: 185,
} as const;

Why a separate driver rather than widening Pulsar

0x3554 is CompX's ODM id, shared by four brands in this repo already. Today a Lamzu Atlantis falls through PulsarHidClient's VGN branch, so it connects as a "Pulsar" device with a lift-off reading that is simply wrong. Adding the Lamzu ids to CLAIMED_VGN_PRODUCT_IDS — the mechanism already there for exactly this — hands them to a driver that knows what they are.

flowchart TD
  D["HID device<br/>vid 0x3554"] --> C{product id}
  C -->|f520 f523 f5bb f522| T[Teevolution]
  C -->|fb56 fb57| V[VGN F2]
  C -->|f58e f58f| A[ATK / VXE]
  C -->|"f50f f50d f510 f517<br/><b>new</b>"| L[LamzuAtlantisHidClient]
  C -->|anything else| P[Pulsar 4K receiver]
  L --> S["brand: Lamzu · LOD 1 mm / 2 mm<br/>rate table with both 1000 Hz encodings"]
  P --> Q["brand: Pulsar · LOD Low/Med/High<br/>0x10 decoded as 2000 Hz"]

Three things the wire does not do by the book

The battery reply lies about its length. Byte 4 says 0x02; four bytes follow. Decoding by the declared length silently drops the voltage, so payload is the full window and declaredLength is reported separately.

04 00 00 00 02 | 64 01 10 82 | …      100%, charging, 4226 mV
             ^^ says 2        ^^ sends 4

The percent byte is authoritative. lamzu-cfg derives the percentage linearly from millivolts between 3,050 and 4,200. At 4,239 mV that reads 100%, where the mouse's own byte — and Lamzu's configurator on screen next to it — both said 95%.

1,000 Hz has two encodings, as on the other Lamzu generations, so pulsarDecodePollingRate is wrong here: it reads 0x10 as 2,000 Hz.

Reads decode both DPI axes

pulsarVgnDecodeDpi returns null unless a stage's two axis bytes are identical — the Pulsar driver only ever writes them in lockstep. A Lamzu configured with separate x and y stores a perfectly valid, correctly checksummed field that would read as corrupt, so reads use a Lamzu decoder that pulls each axis's high bits out of the flags byte (2-3 for x, 6-7 for y). Writes still go through the shared encoder, which flattens the axes; asymmetric writes aren't attempted without hardware to confirm them.

Flash fields

sleepTime (173) is absent from lamzu-cfg's map. Found by diffing the flash image across a change in Lamzu's configurator — 0x06 at a 1-minute timeout, 0x01 at 10 seconds — so the byte counts ten-second units, not seconds.

A field carries a trailing checksum, so value bytes plus that byte sum to 0x55:

// a read asks for one byte more than the field is wide and rejects a bad sum
const field = await this.readRaw(address, length + 1);
if (!lamzuAtlantisFieldIsIntact(field)) throw new Error(`…corrupt value from address ${address}.`);

Identity

Six models share 0x3554:0xf50f, one USB product string (LAMZU Atlantis Pro) and one firmware version. Nothing on the wire separates them, and Lamzu's own configurator solves this by asking the user to pick the model from a list — so the catalog names the family, Lamzu Atlantis, rather than guessing a model.

Hardware

Lamzu Atlantis Mini 4K, firmware 1.24 (0x12 → 01 24, matching the USB bcdDevice and Lamzu's download page), wired 0x3554:0xf50f.

0xf50f is marked verified: true. The three receiver ids come from Lamzu's device table and nothing more — no receiver has been exercised, so neither their rate lists nor the transport itself is established, and they stay verified: false until one is. The rate family is stored per product rather than inferred from the rate ceiling, so the 1K receiver (which tops out at 1,000 Hz exactly like the cable) is not silently assigned an encoding.

Not touched: button remapping, macros, pairing and factory reset. No command id outside the documented set was ever sent — the write path on this firmware includes a factory reset, so unknown ids were not probed.

Protocol groundwork: LeadSun/lamzu-cfg (Apache-2.0/MIT), reverse-engineered from an Atlantis Mini Pro. Full capture notes in docs/lamzu-atlantis-testing.md.

Companion app PR: OpenMouse-Project/openmouse#235

🤖 Generated with Claude Code